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1.0 INTRODUCTION 

In many situations of assembling, debugging, and modifying programs, a cross- 
reference listing is an invaluable aid. This listing is particularly useful 
when a programmer wishes to make changes in a large program or one he does not 
know well . 

A cross-reference is an alphabetical listing of all user-defined symbols with the 
line numbers at which the symbol was defined and used. Thus , the various places 
that a tagged location or an equated symbol is used are easily identified. 
CREF12 provides this facility to the DIAL-MS 1 , user. 

It should be noted that the usefulness of a CREF (CRoss-REFerence) is almost 
directly proportional to the quality of the coding. In particular, the follow- 
ing principles should be used in new cdding in order to make the best use of 
CREF 12 : 

1. Use symbolic references for beta registers, auto-index registers, 
page zero constants and temporaries, and fixed core locations. 

2. Avoid use of large displacements from a tag (e.g., TAD X+12 or 
JMP Y-6) feecause references to X and Y, respectively, rather than 
the locations actually used, will appear in the CREF. 

2.0 ENVIRONMENT 

CREF12 (including its header) occupies seven blocks in the DIAL file area of any 
unit. It is loaded into locations 0 through 2777 of field 1 and is entered at 
200 in field 1. 

3.0 USING CREF.12 

CREF12 is intended for use in conjunction with the LISTAPE pseudo-op of the 
DIAL-MS Assembler. LISTAPE (with a positive argument) produces a normal 

(R 

assembler listing on a mass-storage device, rather than on the console Teletype 
or line printer. The resulting data may then be processed by CREF12 to produce 
a full cross-reference of user-defined symbols and, optionally, the assembly 
listing. 

To use CREF12, insert a LISTAPE n pseudo-op in the program of interest, where 
n is an expression whose value is between 0 and 45, octal, and is taken as the 

Teletype is a registered trademark of Teletype Corporation. 
1 LAP6~DIAL-MS is commonly referred to as DIAL-MS. 
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unit number of a scratch tape (0-7) or disk (10-45) on which the Assembler list- 
ing will be produced. The user must exercise caution in assigning units for 
LIS TAPE because the listing information is written directly on the unit starting 
at block zero without regard to anything else that may be on .the same unit. 
Therefore, unit n should be either a scratch tape or a logical disk devoted to 
scratch work. 

Typing return at any time (after answering the "LISTING [Y OR N] ? " question 
causes CREF12 to return to DIAL-MS. 



3 . 1 Operating Procedures 

1. Set all six sense switches on. Be sure the tape or disk unit 
assigned by the LISTAPE pseudo-op is ready and WRITE ENABLEd. 

2. Assemble the program with the LIST Command (refer to the LAP6-DIAL 
Programmer's Reference Manual, DEC-12-SE2D-D) . 

3. If a printer is to be used for the CREF, it should be ready at 
this time. When the Editor display returns, load CREF12 by 
typing -»-LO CREF12,0^ 

4. The following message is printed: 

UNIT #? 

Type an octal number between 0 and 45, followed by carriage return, 
for the unit on which the listing was written. 

5. The next message is 

LISTING [Y OR N]? 

Type Y if the full assembly listing and CREF are desired; N if only 
the CREF is needed. 

Assuming the specified unit is available and ready, CREF12 will then read the 

listing (printing it if requested) and print the cross-reference table. 
Output will be on a line printer if one is available and ready. 

Otherwise, it will be on the console teletype. 

3 . 2 Error Conditions 

Under some conditions, CREF12 will not be able to produce the cross-reference 
desired. 

1. If there were errors in the assembly, CREF12 may interpret the 
program incorrectly, or may even be unable to process it at 
all. In the latter event, it will print "BAD INPUT" and return 
to DIAL-MS. 

2. If there is a large number of symbols and references, the cross- 
reference table may overflow. In this case, CREF12 prints: 



SYMBOL TABLE OVERFLOW AT LINE XXXX 



where XXXX is the last line number processed. CREF12 then 
prints the cross-reference up to that line, and returns to 
DIAL-MS. This problem Will arise if (NSYM*5 + NREF) is greater 
than 4j094, where NSYM is the number of user-defined symbols in 
the program, and NREF is the number of references to user-defined 
symbols. If there are more than 818, Q symbols, this message 
will occur during the first pass, with XXXX equal to 0000. 

CREF12 will print "BAD INPUT" and return to DIAL-MS. 

3) If the unit specified by the user is invalid, the DIAL-MS 

I/O routines will display NO. The user may type return to get back to DIAL. 

If a program containing a LISTAPE pseudo-op is to be assembled without getting a 
CREF, use the normal assembly procedure with the sense switches off; this 
disables the LISTAPE function. 

4.0 INTERNAL DESCRIPTION 

After reading the DIAL-MS I/O routines into 1000-1111 of field 1, CREF12 requests 

two parameters from the user: the unit from which to read the listing, 

and whether the listing is to be printed; CREF12 then begins its first 

pass over the data. The routine MAIN rewinds the input, initializes counters, 

and calls the subroutines GETLIN and ENDLST to get a line of input and 

check it for the separator between the listing proper and 

the symbol table, respectively. mis separator is a line with one of two 

messages, "NO ERRORS" or "XXXX ERRORS". If the input runs out (indicated by a 

word of zero) before the separator is found, the input is invalid and processing 

is terminated with the message "BAD INPUT". If the separator is found, SYMBUILD 

takes over and reads the symbol table. Each symbol is stored in stripped ASCII 

form in field 0, followed by two words of zero. 

When the end of data is found, control passes to PART 2 , which rewinds the input 
file. MAJOR calls GETLIN and ENDLST to get successive lines from the file and 
test for the end of the listing proper. After checking for the separator, MAJOR 
flows into SCAN, which collects a symbol at NAME, calls NSERCH to search the 
symbol table for it, and (if it finds the symbol) stores the line number with 
the symbol in field 0. Control returns to SCAN until either carriage return, 
slash, or "TEXT" is found. Control then returns to MAJOR to get a new 
line. 

When a separator is found, control transfers to DUMP, which prints a header, then 
reads each symbol from the file. Each symbol and its value are printed, followed 
by the line number at Which the symbol was defined, and then the line numbers 
at which the references to it were made. 

Output is terminated, and control returns to DIAL-MS, when the end of the symbol 
table is found. 
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The functions of minor routines are as follows: 



BOPUP 

CRLF 
GETBLK 

GETC 
GETLIN 
IMOVE 
IPUSH 



ISNUM 



I ZERO 



LIMIT 

NSERCH 

POCTAL 

PUTC 
TTY 

RETCHU 



- Maintains SYSCOUNT to keep track of field 0 utilization and 
issue the message "SYMBOL TABLE OVERFLOW AT LINE XXXX" when 
the symbol table overflows. Called by SCAN when a reference is 
to be added to the symbol table. 

Go to. a new line on the Teletype or line printer. 

- Get 8 blocks from the input file. Used by GETLIN when the input 
buffer is empty, and by MAIN and PART 2 to rewind the input and 
read the first buffer load. 

Obtain the next character from the current line and return it in 
CHAR and the AC. Used by many routines. 

Get a line (a string of characters terminated by zero or line 
feed) from the input file. If LISTSW is non-zero, print it. 



Move a block of data across field boundaries, 
to move a new entry into the symbol table. 



Used by SYMBUILD 



- Move a portion of .the symbol table down. During SYMBUILD, the 
symbol table is built by pushing previous entries down to lower 
core addresses and entering each new symbol at the end of the 
list (at the top of field 0) . During SCAN , references to each 
symbol are stored following the symbol. IPUSH is called to make 
room for each entry. 

Examine the first four characters of the current line. If not 
octal digits, return to P+l. Otherwise, convert them to binary, 
store binary at LINENO, and return to P+2. Called only by MAJOR. 

Search the symbol table, starting at the location addressed by 
TEMP, for a word of zero. If none is found, return to P+l. 
Otherwise, return to P+2 with TEMP pointing to the zero. 
Called by NSERCH to look for the next symbol and by SCAN to find 
the end of the references to the current symbol. 

- Compare the value in the AC to two limits. If the AC is zero, 
return to address in P+3; if AC is out of limits, return to 
address in P+4. If AC is within the limits, return to P+5. Used 
by many routines. 

- Find the symbol table entry which matches the symbol at NAME. 
Return to P+l if no match is found, or to P+2 if successful. 
Called only by SCAN. 

- Print the value in the AC, converted to octal characters. Used 
by BOPUP to print the line number at which overflow occurs and 
by DUMP to print the cross-reference line numbers. 

- Print one character on the output - device. 
Print a character string. 

Check, the keyboard flag and return to DIAL 
if return has been struck. Otherwise just 
clear AC. 
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HOW TO OBTAIN SOFTWARE INFORMATION 



Announcements for new and revised software, as weli as programming notes, software problems, and documenta- 
tion corrections are published by Software Information Service in the following newsletters. 

Digital Software News for the PDP-8 Family 
Digital Software News for the PDP-9/15 Family 
PDP-6/PDP-10 Software Bulletin 



These newsletters contain information applicable to software available from Digital's Program Library. 



Please complete the card below to place your name on the newsletter mailing list. 



Questions or problems concerning DL ; C Software should be reported to the Software Specialist at your nearest DEC 
regional or district sales office. In cases where no Software Specialist is available, please send a Software Trouble 
Report form with details of the problem to: 

Software Information Service 
Digital Equipment Corporation 
146 Main Street, Bldg. 3-5 
Maynard, Massachusetts 01754 

These forms, which are- available without charge from the Program Library, should be fully filled out and accompa- 
nied by teletype output as well as listings or tapes of the user program to facilitate a complete investigation. An 
answer will be sent to the individual and appropriate topics of general interest will be printed in the newsletter. 

New and revised software and manuals, Software Trouble Report forms, and cumulative Software Manual Updates 
are available from the Program Library. When ordering, include the document number and a brief description of 
the program or manual requested. Revisions of programs and documents will be announced in the newsletters and 
a price list will be included twice yearly. Direct all inquiries and requests to: 

Program Library 
Digital Equipment Corporation 
146 Main Street, Bldg. 3-5 
Maynard, Massachusetts 01754 

Digital Equipment Computer Users Society (DECUS) maintains a user Library and publishes a catalog of programs 
as well as the DECUSCOPE magazine for its members and non-members who request it. For further information 
please write to: 

DECUS 

Digital Equipment Corporation 

146 Main Street 

Maynard, Massachusetts O'l 754 



Send Digital's software newsletters to: 

Name 

Company Name 
Address 



My computer is a 



My system serial number is 



PDP-8/1 □ PDP-8/L □ 

LINC-8 □ PDP-12 □ 

PDP-9 □ PDP-15 □ 

PDP-10 □ OTHER Q 

' (if known) 



(zip code) 
Please specify 
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READER'S COMMENTS 



CREF12 

DEC-12-FRZ£-D 



Digital Equipment Corporation maintains a- continuous effort to improve the quality and usefulness of its 
publications. To do this effectively we need user feedback - your critical evaluation of this manual. 

Please comment on thi£ manual's completeness, accuracy, organization, usability, and readability. 



Did you find errors in this manual? 



How can this manual be improved? 



DEC also strives to keep its customers informed of current DEC software and publications. Thus, the following period- 
ically distributed publications are available upon request. Please check the appropriate boxes for a current issue of the 
publication(s) desired. 

O Software Manual Update, a quarterly collection of revisions to current software manuals. 
O Use r's Bookshelf, a bibliography of current software manuals. 

O Program Library Price List, a list of currently available software programs and manuals. 

Please describe your position. . 

Name . _ Organization 

Street Department 



City 



State 



Zip or Country 
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